<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.10"/>
<title>spi: Main Page</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="HTML_custom.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="xlogo_bg.gif"/></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">spi
   </div>
   <div id="projectbrief">Xilinx SDK Drivers API Documentation</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.10 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li class="current"><a href="index.html"><span>Overview</span></a></li>
      <li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
      <li><a href="globals.html"><span>APIs</span></a></li>
      <li><a href="files.html"><span>File&#160;List</span></a></li>
    </ul>
  </div>
</div><!-- top -->
<div class="header">
  <div class="headertitle">
<div class="title">spi Documentation</div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This component contains the implementation of the <a class="el" href="struct_x_spi.html" title="The XSpi driver instance data. ">XSpi</a> component. It is the driver for an SPI master or slave device. It supports 8-bit, 16-bit and 32-bit wide data transfers.</p>
<p>SPI is a 4-wire serial interface. It is a full-duplex, synchronous bus that facilitates communication between one master and one slave. The device is always full-duplex, which means that for every byte sent, one is received, and vice-versa. The master controls the clock, so it can regulate when it wants to send or receive data. The slave is under control of the master, it must respond quickly since it has no control of the clock and must send/receive data as fast or as slow as the master does.</p>
<p>The application software between master and slave must implement a higher layer protocol so that slaves know what to transmit to the master and when.</p>
<p><b>Initialization &amp; Configuration</b></p>
<p>The <a class="el" href="struct_x_spi___config.html" title="This typedef contains configuration information for the device. ">XSpi_Config</a> structure is used by the driver to configure itself. This configuration structure is typically created by the tool-chain based on HW build properties.</p>
<p>To support multiple runtime loading and initialization strategies employed by various operating systems, the driver instance can be initialized in one of the following ways:</p>
<ul>
<li>XSpi_Initialize(InstancePtr, DeviceId) - The driver looks up its own configuration structure created by the tool-chain based on an ID provided by the tool-chain.</li>
<li>XSpi_CfgInitialize(InstancePtr, CfgPtr, EffectiveAddr) - Uses a configuration structure provided by the caller. If running in a system with address translation, the provided virtual memory base address replaces the physical address present in the configuration structure.</li>
</ul>
<p><b>Multiple Masters</b></p>
<p>More than one master can exist, but arbitration is the responsibility of the higher layer software. The device driver does not perform any type of arbitration.</p>
<p><b>Multiple Slaves</b></p>
<p>Multiple slaves are supported by adding additional slave select (SS) signals to each device, one for each slave on the bus. The driver ensures that only one slave can be selected at any one time.</p>
<p><b>FIFOs</b></p>
<p>The SPI hardware is parameterized such that it can be built with or without FIFOs. When using FIFOs, both send and receive must have FIFOs. The driver will not function correctly if one direction has a FIFO but the other direction does not. The frequency of the interrupts which occur is proportional to the data rate such that high data rates without the FIFOs could cause the software to consume large amounts of processing time. The driver is designed to work with or without the FIFOs.</p>
<p><b>Interrupts</b></p>
<p>The user must connect the interrupt handler of the driver, XSpi_InterruptHandler to an interrupt system such that it will be called when an interrupt occurs. This function does not save and restore the processor context such that the user must provide this processing.</p>
<p>The driver handles the following interrupts:</p><ul>
<li>Data Transmit Register/FIFO Empty</li>
<li>Data Transmit FIFO Half Empty</li>
<li>Data Transmit Register/FIFO Underrun</li>
<li>Data Receive Register/FIFO Overrun</li>
<li>Mode Fault Error</li>
<li>Slave Mode Fault Error</li>
<li>Slave Mode Select</li>
<li>Data Receive FIFO not Empty</li>
</ul>
<p>The Data Transmit Register/FIFO Empty interrupt indicates that the SPI device has transmitted all the data available to transmit, and now its data register (or FIFO) is empty. The driver uses this interrupt to indicate progress while sending data. The driver may have more data to send, in which case the data transmit register (or FIFO) is filled for subsequent transmission. When this interrupt arrives and all the data has been sent, the driver invokes the status callback with a value of XST_SPI_TRANSFER_DONE to inform the upper layer software that all data has been sent.</p>
<p>The Data Transmit FIFO Half Empty interrupt indicates that the SPI device has transmitted half of the data available, in the FIFO, to transmit. The driver uses this interrupt to indicate progress while sending data. The driver may have more data to send, in which case the data transmit FIFO is filled for subsequent transmission. This interrupt is particualrly useful in slave mode, while transfering more than FIFO_DEPTH number of bytes. In this case, the driver ensures that the FIFO is never empty during a transfer and avoids master receiving invalid data.</p>
<p>The Data Transmit Register/FIFO Underrun interrupt indicates that, as slave, the SPI device was required to transmit but there was no data available to transmit in the transmit register (or FIFO). This may not be an error if the master is not expecting data, but in the case where the master is expecting data this serves as a notification of such a condition. The driver reports this condition to the upper layer software through the status handler.</p>
<p>The Data Receive Register/FIFO Overrun interrupt indicates that the SPI device received data and subsequently dropped the data because the data receive register (or FIFO) was full. The interrupt applies to both master and slave operation. The driver reports this condition to the upper layer software through the status handler. This likely indicates a problem with the higher layer protocol, or a problem with the slave performance.</p>
<p>The Mode Fault Error interrupt indicates that while configured as a master, the device was selected as a slave by another master. This can be used by the application for arbitration in a multimaster environment or to indicate a problem with arbitration. When this interrupt occurs, the driver invokes the status callback with a status value of XST_SPI_MODE_FAULT. It is up to the application to resolve the conflict.</p>
<p>The Slave Mode Fault Error interrupt indicates that a slave device was selected as a slave by a master, but the slave device was disabled. This can be used during system debugging or by the slave application to learn when the slave application has not prepared for a master operation in a timely fashion. This likely indicates a problem with the higher layer protocol, or a problem with the slave performance.</p>
<p>The Slave Mode Select interrupt indicates that the SPI device was selected as a slave by a master. The driver reports this condition to the upper layer software through the status handler.</p>
<p>Data Receive FIFO not Empty interrupt indicates that the SPI device, in slave mode, has received a data byte in the Data Receive FIFO, after the master has started a transfer. The driver reports this condition to the upper layer software through the status handler.</p>
<p><b>Polled Operation</b></p>
<p>This driver operates in polled mode operation too. To put the driver in polled mode the Global Interrupt must be disabled after the Spi is Initialized and Spi driver is started.</p>
<p>Statistics are not updated in this mode of operation.</p>
<p><b>Device Busy</b></p>
<p>Some operations are disallowed when the device is busy. The driver tracks whether a device is busy. The device is considered busy when a data transfer request is outstanding, and is considered not busy only when that transfer completes (or is aborted with a mode fault error). This applies to both master and slave devices.</p>
<p><b>Device Configuration</b></p>
<p>The device can be configured in various ways during the FPGA implementation process. Configuration parameters are stored in the <a class="el" href="xspi__g_8c.html">xspi_g.c</a> file or passed in via _CfgInitialize(). A table is defined where each entry contains configuration information for an SPI device. This information includes such things as the base address of the memory-mapped device, the number of slave select bits in the device, and whether the device has FIFOs and is configured as slave-only.</p>
<p><b>RTOS Independence</b></p>
<p>This driver is intended to be RTOS and processor independent. It works with physical addresses only. Any needs for dynamic memory management, threads or thread mutual exclusion, virtual memory, or cache control must be satisfied by the layer above this driver.</p>
<pre>
MODIFICATION HISTORY:</pre><pre>Ver   Who  Date     Changes
----- ---- -------- -----------------------------------------------
1.00a rpm  10/11/01 First release
1.00b jhl  03/14/02 Repartitioned driver for smaller files.
1.01a jvb  12/14/05 I separated dependency on the static config table and
                    xparameters.h from the driver initialization by moving
                    _Initialize and _LookupConfig to _sinit.c. I also added
                    the new _CfgInitialize routine.
1.11a wgr  03/22/07 Converted to new coding style.
1.11a  sv  02/22/08 Added the definition of LSB-MSB first option in <a class="el" href="xspi__l_8h.html">xspi_l.h</a>.
1.12a sdm  03/22/08 Updated the code to support 16/32 bit transfer width and
                    polled mode of operation, removed the macros in <a class="el" href="xspi__l_8h.html">xspi_l.h</a>,
                    added macros in <a class="el" href="xspi_8h.html">xspi.h</a> file, moved the interrupt
                    register/bit definitions from <a class="el" href="xspi__i_8h.html">xspi_i.h</a> to xpsi_l.h.
                    Even for the polled mode of operation the Interrupt Logic
                    in the core should be included. The driver can be put in
                    polled mode of operation by disabling the Global Interrupt
                    after the Spi Initialization is completed and Spi is
                    started.
2.00a sdm  07/30/08 Updated the code to support 16/32 bit transfer width and
                    polled mode of operation, removed the macros in <a class="el" href="xspi__l_8h.html">xspi_l.h</a>,
                    added macros in <a class="el" href="xspi_8h.html">xspi.h</a> file, moved the interrupt
                    register/bit definitions from <a class="el" href="xspi__i_8h.html">xspi_i.h</a> to xpsi_l.h.
                    Even for the polled mode of operation the Interrupt Logic
                    in the core should be included. The driver can be put in
                    polled mode of operation by disabling the Global Interrupt
                    after the Spi Initialization is completed and Spi is
                    started.
2.01a sdm  08/22/08 Removed support for static interrupt handlers from the MDD
	      file
2.01b sdm  04/08/09 Fixed an issue in the XSpi_Transfer function where the
                    Global Interrupt is being enabled in polled mode when a
                    slave is not selected.
3.00a ktn  10/22/09 Converted all register accesses to 32 bit access.
	      Updated driver to use the HAL APIs/macros.
	      Removed the macro XSpi_mReset, XSpi_Reset API should be
	      used in its place.
	      The macros have been renamed to remove _m from the name
	      XSpi_mIntrGlobalEnable is renamed XSpi_IntrGlobalEnable,
	      XSpi_mIntrGlobalDisable is now XSpi_IntrGlobalDisable,
	      XSpi_mIsIntrGlobalEnabled is now XSpi_IsIntrGlobalEnabled,
	      XSpi_mIntrGetStatus is now XSpi_IntrGetStatus,
	      XSpi_mIntrClear is now XSpi_IntrClear,
	      XSpi_mIntrEnable is now XSpi_IntrEnable,
	      XSpi_mIntrDisable is now XSpi_IntrDisable,
	      XSpi_mIntrGetEnabled is now XSpi_IntrGetEnabled,
	      XSpi_mSetControlReg is now XSpi_SetControlReg,
	      XSpi_mGetControlReg is now XSpi_GetControlReg,
	      XSpi_mGetStatusReg is now XSpi_GetStatusReg,
	      XSpi_mSetSlaveSelectReg is now XSpi_SetSlaveSelectReg,
	      XSpi_mGetSlaveSelectReg is now XSpi_GetSlaveSelectReg,
	      XSpi_mEnable is now XSpi_Enable,
	      XSpi_mDisable is now XSpi_Disable.
3.01a sdm  04/23/10 Updated the driver to handle new slave mode interrupts
	      and the DTR Half Empty interrupt.
3.02a sdm  03/30/11 Updated to support axi_qspi.
3.03a sdm  08/09/11 Updated the selftest to check for a correct default value
	      in the case of axi_qspi - CR 620502
	      Updated tcl to generate a config parameter for C_SPI_MODE
3.04a bss  03/21/12 Updated <a class="el" href="struct_x_spi___config.html" title="This typedef contains configuration information for the device. ">XSpi_Config</a> and <a class="el" href="struct_x_spi.html" title="The XSpi driver instance data. ">XSpi</a> instance structure to support
	      XIP Mode.
	      Updated XSpi_CfgInitialize to support XIP Mode
	      Added XIP Mode Register masks in <a class="el" href="xspi__l_8h.html">xspi_l.h</a>
	      Tcl Script changes:
	      Added C_TYPE_OF_AXI4_INTERFACE, C_AXI4_BASEADDR and
	      C_XIP_MODE to config structure.
	      Modified such that based on C_XIP_MODE and
	      C_TYPE_OF_AXI4_INTERFACE parameters C_BASEADDR will
	      be updated with C_AXI4_BASEADDR.
	      Modified such that C_FIFO_EXIST will be updated based
	      on C_FIFO_DEPTH for compatability of the driver with
	      Axi Spi.
3.05a adk  18/04/13 Updated the code to avoid unused variable
		 warnings when compiling with the -Wextra -Wall flags
		 In the file <a class="el" href="xspi_8c.html">xspi.c</a>. CR:705005.
3.06a adk  07/08/13 Added a dummy read in the CfgInitialize(), if startup
                    block is used in the h/w design (CR 721229).
3.07a adk  11/10/13 Fixed CR:732962 Changes are made in the <a class="el" href="xspi_8c.html">xspi.c</a> file
4.0   adk  19/12/13 Updated as per the New Tcl API's
4.1	bss  08/07/14 Modified XSpi_Transfer in <a class="el" href="xspi_8c.html">xspi.c</a> and LoopbackTest in
	      <a class="el" href="xspi__selftest_8c.html">xspi_selftest.c</a> to check for Interrupt Status
	      register Tx Empty bit instead of Status register
	      CR#810294.</pre><pre></pre> </div></div><!-- contents -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Copyright &copy; 2015 Xilinx Inc. All rights reserved.</li>
  </ul>
</div>
</body>
</html>
